API Documentation
*****************

Hydra Paste uses a RESTful API with extensions for JSON data when applicable.

General Concepts
================

In Hydra Paste, the way a file is identified is by its *short ID*.
A file's short ID is the Radix66 encoded version of a longer, internal id.
All you need to know is the file's short ID.

An example of a file's short ID is http://paste.hydra.ws/p/F0uy. For this paste,
``F0uy`` is the short ID of the file. This ID will be used as an example for the
remainder of this document.


Files
=====

.. _upload-file-api:

Uploading a File
----------------

You may upload a file to Hydra Paste with the following request format: ::

    POST /api/upload


.. note::
    For file uploads, the parameters are set into two types: *form* data and
    *file* data.  The contents of a file such as an image or video uploaded to
    Hydra Paste are uploaded as *file* data.  On the other hand, text files can
    be uploaded as *file* data. This is one of the complexities of HTTP.  Just
    know that if you're uploading raw text to use the ``text`` form option, and
    for uploading files to use the ``upload`` parameter for *file* data.

The ``Content-Type`` of uploaded *file* data should  ``multipart/form-data``.
If you're trying to upload *file* data and that isn't the encoding, you're
doing something wrong. If you send login information with the upload, then the
paste is attached to your account. For information about authentication, see 
:ref:`auth`.

Form data
^^^^^^^^^
- ``expires`` - The time in seconds, in UNIX time, whenever the paste uploaded should expire. If this value is ``0``, then the file will not expire. If this is left blank, the server will automatically pick a value.  If the value starts with a ``+``, then the numbers afterwards will be the number of seconds in the future the paste should expire in.  For example, ``+60`` will make the paste expire in one minute.
- ``title`` - Self-explanatory; what to call the paste.
- ``text`` - The text body of the file.  Only supported for text documents.  This
  is what is used with the web UI. **NB:** This is only support on text uploads
  with no attached files
- ``mimetype`` - the ISO mimetype of the object. The is completely optional, and Hydra Paste will automatically detect the paste's mimetype if this is not specified. Only use this to force the mimetype of an uploaded file, such as source code. This will break stuff if you use it wrong.

File Data
^^^^^^^^^
- ``upload`` - Self-explanatory; this is the file you upload.


Modifying an Uploaded File
--------------------------

This is essentially the same as :ref:`upload-file-api`, except that there is an addition
parameter, ``key`` that should coorespond to the key of the file being overwritten.
Authentication is required for this command, *obviously*. You also can only modify
files that you have created (*duh*). Doing either of these two *No-Nos* will result
in a 400 error (*this documentation is starting to seem pretty damn obvious*).

.. _api-file-downloads:

File Downloads
--------------

You may download a file in the following manner: ::

    GET /api/file/FILEID

Where `FILEID` is the short ID of the file.

.. _file-info:

File Information
----------------

You can get information about a file in to fashions: the RESTful way and the good
old JSON way.

The RESTful Way
^^^^^^^^^^^^^^^

A file's information is retrieved in the following manner: ::

    HEAD /api/file/FILEID

Where `FILEID` is the short ID of the file.

* ``X-Paste-User`` - The user who uploaded the file.
* ``X-Paste-Expires`` - The UNIX time of when the paste expires (if 0, the paste
  w`ill never expire).
* ``X-Paste-Filename`` - The filename of the paste (blank if uploaded via
  t`he web UI).
* ``X-Paste-Title`` - The title of the paste.
* ``X-Paste-Views`` - The number of views the paste has received.
* ``X-Paste-Short-Key`` - The short ID of the file.

Another interesting point to note is that these headers are also sent whenever
downloading a file. See the :ref:`api-file-downloads` section for more information.

.. _file-info-json: 

The JSON Way
^^^^^^^^^^^^

You may also retrieve a JSON dictionary witht he following request: ::

    GET /api/file/info/FILEID

This will return a JSON dictionary of information about the file in the following
format: ::

    {
        user: "anonymous"
        key: "H4",
        title: "Harold With Hammer",
        views: 112,
        filesize: 36415,
        filetype: "image/jpeg",
        expires: 0,
        time: 1425704291,
        filename: "1424000592418.jpg"
    }

* ``user`` - The username of the uploader.
* ``key`` - The ID of the file.
* ``title`` - The title of the paste. Sometimes, this value will be null.
* ``views`` - The number of times this paste has been viewed.
* ``filesize`` - The size of the paste in bytes.
* ``filetype`` - The mime type of the paste.
* ``expires`` - The Unix time when the paste will expire (``0`` means never).
* ``time`` - The Unix time when the paste was uploaded.
* ``filename`` - The filename of the original paste. Text uploads will have a ``null`` filename.


Deleting a File
---------------

To delete a file, you may use either a POST request or a DELETE request (good old REST!)

For DELETE, use the following with an ``Authorization`` header as described in :ref:`auth` ::

    DELETE /api/file/FILEID

For POST, use the following with the standard ``username`` and ``password`` parameters ::

    POST /api/file/rm/FILEID

.. important::
    In order to be able to delete a paste, you must have uploaded it while using a registered
    account. Currently, anonymous file deletion is disabled.

User Information
================

This section will describe the portion of the API found on the ``/api/user`` path.

.. _auth:

User Authentication
-------------------

To authentication on Hydra Paste is consistent across the API. Simply send
some POST data with the following fields:

- ``username`` - The user you want to authenticate as.
- ``password`` - The password to authenticate with.

Alternatively, you can use the ``Authorization`` header, in the following format ::

    user-pass username:password

Where ``username`` and ``password`` are replaced with their appropriate values

To login anonymously, set ``username`` to ``anonymous``. When using an API
such as described in :ref:`upload-file-api`, simply send the login information
alongside the other parameters in the same request. Hydra Paste will take care
of everything for you.

.. note::
    Anonymous login isn't available across the whole API. There are some
    APIs features disabled for anonymous login, most notably the ``/api/user``
    subset. It is reccomended to register an account to make full use of
    the Hydra Paste API.

Listing Uploaded Files
----------------------

To retrieve a JSON dicitonary of your uploaded files, use the following request
with login data: ::

    POST /api/user/

This will return a JSON dictionary in a format like this: ::

    {
        'KEY1': {
                    //file info here
                },
        'KEY2': {
                    //file2 info here
                },
        // and so on...
    }

Each key value will be the short key of the paste, and the contents of the key will
be a dictionary of items as described in :ref:`file-info-json`.
